NetCloak 3.0 User's Guide: Commands: Security

	Version 3.0 User's Guide

Commands: Security	Previous \| Next> Contents

<INSERT_DOMAIN>

This command will place the user's address, as text, into your document. INSERT_DOMAIN may be a somewhat misleading name (it might better be called INSERT_ADDRESS), but is used to keep the naming consistent with the HIDE and SHOW commands where a sub-domain is normally specified as opposed to a complete address. Here is an example:

    Your TCP/IP address is: <INSERT_DOMAIN>.

If you have turned on your Web server's option to look up the DNS name associated with the client address for each connection, the INSERT_DOMAIN command will insert the DNS name found by the Web server. Otherwise, it will insert the numeric IP address of the client.

<HIDE_DOMAIN operator domain1 domain2 ...>
<SHOW_DOMAIN operator domain1 domain2 ...>

Any HTML text that follows HIDE_DOMAIN will be hidden from those people in the domains that satisfy the comparison operator, until the next SHOW or HIDE command. Similarly, any HTML text that follows SHOW_DOMAIN will be shown to users in those domains. You can use the HIDE/SHOW_DOMAIN commands to tailor the content of your web pages to the people within your intranet or domain.

Multiple domains may be specified. For example, to hide text from sub-domains 123.456 and 123.89, use:

    <HIDE_DOMAIN BEGINS 123.456 123.89>

Each domain must be separated by whitespace, and you may specify any number of domains (limited only by the maximum length of a NetCloak command - currently 4096 characters).

When the comparison operator is omitted from the command, NetCloak performs a "begins with" text comparison. This means that the address of the user accessing the page must begin with the given domain parameter for text to be hidden (or shown in the SHOW_DOMAIN command).

When performing text comparisons, you may specify as much or as little of the domain address as you like. For example:

    <HIDE_DOMAIN 123.456.>

and

    <HIDE_DOMAIN 123.>

would both hide text from the browser with the address of "123.456.78.9". The second command would also hide the text from a browser at the address "123.654.932.10", but the first would not. Specifying more of the address just makes the command more restrictive.

If you use a numeric comparison operator (==, LT, LT=, GT, GT=), you must specify the IP address parameters fully, because NetCloak converts the client address and each parameter to an integer value to perform the comparison. Using a numeric comparison operator allows you to check for IP addresses within a certain range which may be less than a full class C block of addresses. For example, to show some text only to clients in the address range 123.45.67.1 through 123.45.67.100, you would use:

    <SHOW>    <HIDE_DOMAIN LT 123.45.67.1>    <HIDE_DOMAIN GT 123.45.67.100>    This text is only shown to clients within the specified IP address range.
    <SHOW>

To use the HIDE/SHOW_DOMAIN commands with domain names instead of numeric IP addresses, you must turn on DNS lookups in your Web server (in WebSTAR 2.x, check the "Use DNS" setting in the "Misc. Settings" dialog), then use one of the text comparison operators. For example, the command

    <HIDE_DOMAIN ENDS .maxum.com>

would hide text from anyone coming from the domain "maxum.com" (as long as you have your Web server set to resolve domain names).

Note: using a "contains" comparison can lead to unexpected results. For example, if you wanted to hide text from all clients in the ".com" domain you might use:

    <HIDE_DOMAIN CONTAINS .com>

This would work as you would expect, but would also hide the text following it from a client in the domain "home.common.edu" or "many.computers.se" which may be undesirable. When using HIDE_DOMAIN this way, you should be as specific as possible. Usually, a "begins with" or "ends with" comparison operator is a better choice.

For backward compatibility with versions of NetCloak prior to 3.0, the syntax:<HIDE_DOMAIN_C domain1 domain2 ...> is still supported, operating identically to a<HIDE_DOMAIN CONTAINS domain1 domain2 ...> command. The new syntax is preferred.

<INSERT_USERNAME>

This command will place the username specified for basic authentication into your document at the specified point. The example below inserts the user's name:

    Hello <INSERT_USERNAME>!

The username inserted is whatever the user entered into an authentication dialog box displayed by their Web browser. Normally the user will not have entered a username or password unless they have loaded a page with a NetCloak REQUEST_PASSWORD command or protected by a realm or other security on your Web server. Until the user enters a username and password, the username will be blank.

<HIDE_USERNAME operator user1 user2 ...>
<SHOW_USERNAME operator user1 user2 ...>

HIDE_USERNAME hides the HTML text that follows it from clients who have entered a username that satisfies the comparison to any one of the specified username parameters. SHOW_USERNAME shows the HTML text to clients whose username satisfies the comparison.

If the comparison operator is omitted, an exact text match (an "is" comparison) is required. However, letter case is ignored, so "bob" and "BoB" are considered an exact match.

As with other NetCloak commands, you may specify multiple usernames. For example, to hide text from everyone who has entered the username "John" or "Bob", use:

    <HIDE_USERNAME IS JOHN BOB>

To see if the user has entered a name, you can use the command with no parameters, or you can use the EXISTS comparison operator. This will hide/show text from anyone who has entered any username. The example below will display the username, or a message if the user has not entered one yet.

    <HIDE><SHOW_USERNAME>    Hello <INSERT_USERNAME>!
    <SHOW><HIDE_USERNAME>    You haven't entered a user name yet.
    <SHOW>

<INSERT_PASSWORD>

This command will place the user's password, as text, into your document at the specified point. For example:

    You entered the password <INSERT_PASSWORD>

This command should be used with caution, as it displays sensitive information on a page. Note that the actual password, not a series of bullets, asterisks, or blanks, will be displayed in plain text on the user's browser.

<HIDE_PASSWORD operator passwd1 passwd2...>
<SHOW_PASSWORD operator passwd1 passwd2...>

HIDE_PASSWORD hides the HTML text from users whose password satisfies the comparison with any one of the given passwords. SHOW_PASSWORD shows text to those same users.

If the comparison operator is omitted, an exact text match (an "is" comparison) is required. As always, capitalization is ignored.

As with the other NetCloak commands, you may specify a full or partial password, and you may specify any number of passwords in the command. For example, to hide text from all people with the password "MOOF":

    <HIDE_PASSWORD MOOF>

You can use the command without parameters, or with the EXISTS comparison operator, to see if the user has entered any password. The command <HIDE_PASSWORD>, used by itself, will hide text from anyone who has entered any password. The following example will display the user's password if they have entered one, or a message if they haven't.

    <HIDE><SHOW_PASSWORD>    Password confirmed as: <INSERT_PASSWORD>.
    <SHOW><HIDE_PASSWORD>    You have not entered a password yet.
    <SHOW>

<REQUEST_PASSWORD prompt user1,pass1 user2,pass2 ...>

This command allows you to request a password from the user for a page. If a valid username and password are not entered, NetCloak will return the No Access page instead of the requested page.

The prompt parameter used in this command is sent to the browser and will be displayed in the username/password dialog box presented to the user. The prompt text is typically displayed by the browser with a message like "Please enter a password for [prompt]."

In addition, you can specify the valid usernames and passwords right inside the REQUEST_PASSWORD command. To specify a user, enter the username and password within a pair of double-quotes, separated only by a comma (no spaces). For example, the username "John" with a password of "Moof" would be defined as "John,Moof".

To allow "John" and a couple of other people access to a page, you might use a command like:

    <REQUEST_PASSWORD "Name" "John,Moof"    "Bob,Whopper" "Dawn,fbr192">

The REQUEST_PASSWORD command requires an exact match between the specified parameters and the username and password but ignores capitalization. The command:

    <REQUEST_PASSWORD "my server" "lo,go">

would allow a username of "Lo" or "LO" but not "Lonnie" or "Carlos", and would allow a password of "Go" or "GO" but not "gone" or "fargo".

Note that the password request can be conditional when used in conjunction with HIDE and SHOW commands. Whenever text is hidden, the REQUEST_PASSWORD command will also be hidden and therefore not activated. In the example above, we could allow everyone access to the page on the weekend, but only allow John, Bob, and Dawn access during the week:

    <HIDE_DAY BEGINS SAT SUN>    <REQUEST_PASSWORD "Weekday Access" "John,Moof" 
    "Bob,Whopper" "Dawn,fbr192">    <SHOW>

On Saturday and Sunday, the REQUEST_PASSWORD command will be hidden, allowing everyone access to the page. During the week, a username and password will be required to gain access to the page.

Note that NetCloak's REQUEST_PASSWORD command is completely independent from your Web server's built-in security or any security add-ons. In many cases, NetCloak is a simpler and more reliable way to secure a single page than realm-based or other security built into the Web server. With the SHOW_USERNAME and SHOW_PASSWORD commands, NetCloak also allows you to apply password security to portions of an HTML page.

How it works: The REQUEST_PASSWORD command may seem somewhat like magic, but it is really quite simple. When NetCloak encounters a REQUEST_PASSWORD command in a page, it first checks to see if the incoming request from the user's web browser already includes a username and password that matches one of the username,password pairs in the command. If no match is found, the rest of the page is ignored. Instead of returning the page, NetCloak sends an "Authorization Required" response to the browser, which includes a special HTTP response header along with the contents of the configured "No Access" page. When this special response is received by the browser, it recognizes it as a request to display the username/password dialog box to the user, and does so. If the user then enters a valid username and password into the dialog box, the same page containing the REQUEST_PASSWORD command is simply re-requested by the browser, but this time it includes the required username and password in the request, so NetCloak displays the page. The browser will then send the username and password in every subsequent request until the browser is quit by the user. When the user cancels the username/password dialog box, the browser simply displays the contents of the "No Access" page it has already received from NetCloak.


Copyright © 1996-1999 Maxum Development Corporation http://www.maxum.com/	Previous \| Next> Contents

Commands: Security